.\" Copyright (c) 2013-2016 Plowshare Team
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 3 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.

.TH "plowprobe" "1" "July 13, 2016" "GPL" "Plowshare for Bash 4"

.SH NAME
plowprobe \- Gather information from file sharing download links

.SH SYNOPSIS
.B plowprobe
[\fIOPTIONS\fP]...
[\fIMODULE_OPTIONS\fP]...
\fIURL\fP|\fIFILE\fP...

.SH DESCRIPTION
.B plowprobe
is a command-line tool designed for retrieving metadata from file-sharing
download links. Information are printed on stdout (only alive links). Provided links can also be downloaded with plowdown(1).

.\" ****************************************************************************
.\" * Options                                                                  *
.\" ****************************************************************************
.SH OPTIONS

.SS Common options
.TP
.BI -i, " " --interface= IFACE
If your machine has several network interfaces, force using \fIIFACE\fR interface.
.TP
.BI "   " " " --printf= FORMAT
Print results (on stdout) in a given format (for each non-dead link). Default format string is \fI"%F%u%n"\fR. Interpreted sequences are:
.RS
.TP
\fI%%\fR
raw % character
.TP
\fI%c\fR
probe function return status (0 for success, 13 for dead link, see list below)
.TP
\fI%f\fR
filename (can be empty string)
.TP
\fI%F\fR
empty if \fB%f\fR is empty, or alias to "\fB# %f%n\fR".
.TP
\fI%h\fR
filehash (can be empty string if not available). Usually MD5 or SHA1. If hoster supports several algorithms, the longest digest is used.
.TP
\fI%i\fR
file identifier (can be empty string if not available). Usually included in input URL.
.TP
\fI%m\fR
module name
.TP
\fI%n\fR
newline
.TP
\fI%s\fR
filesize (positive integer) in bytes (can be empty string if not available). Note: It's often approximative.
.TP
\fI%t\fR
tabulation character
.TP
\fI%T\fR
file timestamp (can be empty string if not available). Unix epoch time is preferred.
.TP
\fI%u\fR
download (source) url
.TP
\fI%U\fR
same as \fB%u\fR but url is escaped for JSON usage
.TP
\fI%v\fR
alternate or refactored download url.
This can be for example fixing primary hostname (to avoid HTTP 301 redirection), or force HTTPS protocol. \
If not available, alias to \fB%u\fR.
.TP
\fI%V\fR
same as \fB%v\fR but url is escaped for JSON usage
.P
Note: Metadata are often not fully available from hosters nor implemented by all modules.
.SS Logging options
.TP
.BI -v, " " --verbose= LEVEL
Set output verbosity level:
.RS
\fB0\fR  none,
.RE
.RS
\fB1\fR  errors,
.RE
.RS
\fB2\fR  notice (default behavior),
.RE
.RS
\fB3\fR  debug,
.RE
.RS
\fB4\fR  report (very noisy, log HTML pages).
.RE
.TP
.B -q, --quiet
Alias for \fB-v0\fR. Do not print any debug messages.
.SS Miscellaneous options
.TP
.B "   " --no-color
Disables log messages (stderr only) output coloring.
.TP
.B "   " --follow
If no module is found for link, follow HTTP redirects (curl \-L). Default is disabled.
.TP
.B "   " --get-module
Echo module name for each URL and exit. Faster than \fB--printf=%m\fR. Useful for wrappers.
.TP
.B "   " --no-curlrc
Do not use curl config file (~/.curlrc).
.TP
.BI "   " " " --curlrc= FILE
Force using an alternate curl configuration file. Replaces ~/.curlrc if it exists. This option has no effect when
.B --no\-curlrc
is defined.
.TP
.B "   " --no-plowsharerc
Do not consider any configuration file.
.TP
.BI "   " " " --plowsharerc= FILE
Force using an alternate configuration file (instead of per-user or systemwide plowshare.conf). This option has no effect when
.B --no\-plowsharerc
is defined.
.TP
.B "   " --modules
Display all supported module names (one per line) and exit. Useful for wrappers.
.SS Generic program information
.TP
.B -h, --help
Display this help and exit.
.TP
.B -H, --longhelp
Display complete help (with module options) and exit.
.TP
.B "   " --version
Output version information and exit.

.\" ****************************************************************************
.\" * Modules options                                                          *
.\" ****************************************************************************
.SH "MODULE OPTIONS"

.P
There is none yet!

.\" ****************************************************************************
.\" * Files                                                                    *
.\" ****************************************************************************
.SH "FILES"
.TP
.I ~/.config/plowshare/plowshare.conf
This is the per-user configuration file.
.TP
.I /etc/plowshare.conf
Systemwide configuration file.
.PP
The file format is described in
.BR plowshare.conf (5).
.TP
.I ~/.config/plowshare/modules.d/
User directory considered when searching for modules at startup
(plowprobe will try to open \fB~/.config/plowshare/modules.d/*/config\fR). One file per module (hoster).

.\" ****************************************************************************
.\" * Environment Variables                                                    *
.\" ****************************************************************************
.SH "ENVIRONMENT VARIABLES"
The following environment variables may affect plowprobe:
.TP
.I HOME
Search for user configuration directory in \fB~/.config/plowshare\fR (see FILES section above).
If found, \fB~/.curlrc\fR will be used (use \fB--no-curlrc\fR to disable it).
.TP
.I PLOWSHARE_CURL
Specifies an alternate curl command (\fB$PATH\fR search is considered). If not defined, \fBcurl\fR is used.
.TP
.I XDG_CONFIG_HOME
The directory to store user configuration files. If not defined, \fB~/.config\fR is assumed.

.\" ****************************************************************************
.\" * Exit codes                                                               *
.\" ****************************************************************************
.SH "EXIT CODES"

Possible exit codes are:
.IP 0
Success. Folder contain one or several files.
.IP 1
Fatal error. Upstream site updated or unexpected result.
.IP 2
No available module (provided URL is not supported).
.IP 3
Network error. Mostly curl related.
.IP 8
System generic error.
.IP 10
Link alive but temporarily unavailable.
.IP 11
Link alive but requires a password.
.IP 12
Link alive but requires some authentication (private or premium link).
.IP 13
Link is dead.
.IP 15
Unknown command line parameter or incompatible options.
.PP
If
.B plowprobe
is invoked with multiple links and one or several errors occur, the first error code is returned added with 100.

.\" ****************************************************************************
.\" * Authors / See Also                                                       *
.\" ****************************************************************************
.SH AUTHORS
Plowshare was initially written by Arnau Sanchez. See the AUTHORS file for a list of some of the many other contributors.

Plowshare is (C) 2010-2016 The Plowshare Team
.SH "SEE ALSO"
.BR plowdown (1),
.BR plowup (1),
.BR plowdel (1),
.BR plowlist (1),
.BR plowshare.conf (5),
.BR plowmod (1).
